Relates to #982 , #986

Upstream issue: synonymdev/ldk-node#94

This PR hardens LDK node teardown so it cannot orphan, deadlock, or overlap the native node:

1. Releases the LDK node handle deterministically on stop instead of leaving it to the garbage collector, with the wait bounded so a stuck free_node can never brick startup
2. Makes teardown non-cancellable, so a cancelled caller (including one cancelled during listener cleanup) can't abandon it halfway
3. Fixes a self-join deadlock when a stop or listener re-arm is requested from inside an LDK event handler
4. Gates rebuild and destructive storage work on the previous node's release so native lifetimes never overlap, and moves config-change recovery to the background so that gate never blocks the user-facing error
5. Stops tearing the node down and rebuilding it when the app is only briefly backgrounded

Description

Play Vitals reports a SIGABRT on mainnet as the top production crash cluster. Symbolicating it locally against the unstripped libldk_node.so for the shipped ldk-node-android version resolved every frame and gave a clear cause:

#19 ldk_node::runtime::spawn_background_task  (chain-sync task, tokio worker thread)
#14 drop_slow<ElectrumRuntimeClient>          ← last Arc released here
#13 drop_in_place<ldk_node::runtime::Runtime / RuntimeMode>
#12 drop_in_place<tokio::runtime::Runtime → BlockingPool>
#11 tokio blocking/shutdown.rs:51 → panic: "Cannot drop a runtime in a context
    where blocking is not allowed"

The defect itself is upstream: ldk-node's chain-sync task drops the last reference to the Electrum client, which owns the tokio runtime, while running on a worker thread of that same runtime. Release Rust aborts on panic, so the process dies with no catchable error. That is filed as synonymdev/ldk-node#94 and this PR does not fix it. What this PR fixes is the Android teardown that made the window wide, non-deterministic, and prone to overlapping native lifetimes.

Deterministic, bounded, non-cancellable release

Stopping the node cleared the reference but never destroyed the handle, so the native node stayed alive until the garbage collector freed it on the finalizer thread at an arbitrary later moment, potentially while a new node was already running. The handle is now released as part of the stop itself.

The release is bounded, not unconditionally synchronous. free_node returns in tens of milliseconds for a healthy node but blocks for tens of seconds when a failed start left the node's background tasks wedged (measured: ~38 ms healthy vs ~40 s wedged). So the release runs on the IO dispatcher and the stop waits on it only up to a short timeout — long enough that a healthy release completes inline, but bounded so the lifecycle state (Stopped) is published promptly rather than blocking behind a wedged drain.

Teardown was also abandonable. The stop ran through a cancellable context and was triggered from a ViewModel scope, so an activity finishing mid-stop left a live native node orphaned with the lifecycle state stranded. The whole teardown — including the listener cleanup join at the top — is now non-cancellable once committed. Reading ldk-node also showed the stop path could not fail the way the code assumed: it reports an error only when the node is already stopped and swallows every internal failure, so a failed stop no longer rethrows and skips the release.

Listener lifecycle safety

WakeNodeWorker calls stop() synchronously from its registered LDK event handler, which runs on the listener job. listenerJob.cancelAndJoin() then waited on the very job it was running on — a self-join. The same shape applied to startEventListener()'s re-arm. A stop from inside a handler now skips joining its own job (detected via currentCoroutineContext(), not the shadowing class-scope coroutineContext), and a re-arm from inside a handler is a no-op. The listener loop also keys on node identity, not just the shared shouldListenForEvents flag (now @Volatile), so a racing start() cannot make the old loop poll a node destroy() already freed. startEventListener uses runSuspendCatching so it no longer silently swallows the cancellation.

Overlap prevention: release gate + non-blocking recovery

Even with a bounded stop, the old node can still be draining after Stopped is published. Rebuild, wipeStorage(), resetNetworkGraph(), and the pathfinding-scores VSS deletes now wait on the previous node's release before touching storage, so a new node never builds over — or a delete never races — storage the old node still owns. That wait is itself bounded (~90 s, comfortably above the observed ~40 s wedge): a stuck free_node throws NodeReleaseTimeout rather than proceeding (which would overlap) or blocking forever (which would permanently brick every future rebuild).

Because the gate deliberately makes a wedged-node rebuild wait for the drain, the Electrum/RGS "wrong server" recovery would otherwise block the user-facing error behind ~40 s. So restartWithElectrumServer/restartWithRgsServer now surface the failure immediately and run the recovery restart on the repository's process-lifetime scope; the gate still holds inside that background recovery. An earlier revision that waited for the release inline turned a 0.6 s recovery stop into a 40 s one and timed out the @settings_10 E2E; this keeps the gate and its overlap guarantee while surfacing the error in ~23 s.

Brief-background debounce

Backgrounding the app stopped the node immediately, so a short task switch cost a full stop plus a full rebuild. The stop from backgrounding is now deferred by a few seconds and cancelled if the app returns. Only the backgrounding path is deferred; the notification stop action, service teardown, notification worker, and restore migration all still stop immediately. The deferred stop is owned by the repository's process-lifetime scope so it cannot be silently dropped when the activity goes away, and every start() cancels a pending stop up front so a start that short-circuits on its guards can't leave one to fire against a foregrounded node.

Preview

QA Notes

Manual Tests

• 1a. Home → background the app and return within ~2s: no node teardown or rebuild, wallet stays responsive.
  • 1b. Background and wait past the window, then return: node stops, then rebuilds and reaches started.
• 2. regression: Background Payments → enable Get paid when Bitkit is closed and Keep Bitkit active in background → background the app: node keeps running, no teardown.
• 3. regression: Node notification → tap Stop: node stops immediately and the app task is removed.
• 4. regression: Relaunch after a notification stop: node rebuilds and reaches started.
• 5. regression: Settings → Lightning → restart node, and Electrum/RGS server change to a valid server: node stops and restarts normally.
• 6. regression: Receive a Lightning payment in the background (app closed, Background Payments on): payment is received and the notification is delivered.
• 7. Settings → Advanced → Electrum → enter an unreachable server → Connect: the error surfaces promptly (does not hang for the full recovery), and the node recovers to the previous server on its own.

Automated Checks

• Release + teardown coverage in LightningServiceTest.kt: deterministic handle release, release when the node is already stopped / when node stop throws, the no-node case, no double release, and teardown completing when the caller is cancelled (including cancellation during listener cleanup).
• Listener-safety coverage in LightningServiceTest.kt: a stop from inside an event handler completes without self-join deadlock, a re-arm from inside a handler keeps the listener running, an external stop cancels and joins the listener, and the loop stops polling a node once it is swapped out (no use-after-free).
• Release-gate coverage in LightningServiceTest.kt: rebuild (setup), wipeStorage, and resetNetworkGraph each wait for the previous release before proceeding; the gate adds no latency when no release is pending; the gate throws instead of blocking forever when the release never finishes; and the stop returns within its bound while the release is wedged. These use a real IO dispatcher plus a controllably delayed destroy().
• Repo coverage in LightningRepoTest.kt: deferred stop timing and cancellation, a foreground/background cycle within the window never stopping the node, and restartWithElectrumServer surfacing failure before the background recovery completes. WalletViewModelTest.kt: a foreground start cancels a pending deferred stop even while startup is still active.
• Each new regression test was verified load-bearing by reverting its fix and confirming it fails (or, for the unbounded-gate case, hangs) before restoring.
• Device validation on the emulator, backgrounding for 1–8 seconds: under the window the node stays running and start is skipped; past it the log order is always Stopping node… → Node stopped → Building node… → Node started, confirming teardown completes before startup on the healthy path.
• Device validation of the foreground-service path: with background payments and keep-active enabled, backgrounding produced no stop and the node kept processing LDK events.
• Device validation of the notification stop action (immediate, no double-stop from service teardown) and of a background Lightning receive.
• Device validation of the release gate and non-blocking recovery against a server that accepts TCP but never completes the TLS handshake (the @settings_10 "wrong Electrum server" condition). The error surfaces in ~23 s (under the 30 s E2E budget) while the gate holds the background rebuild until the wedged node drains, with no SIGABRT/tombstone:

  Changing electrum server (connect)
  Node stopped                                 (old node, ~0.6s)
  Building node…                               (wrong server)
  Failed config change, recovering in background…   ← error surfaces (~23s)
  Waiting for previous node release to finish…      ← gate, in background
  Building node…                               (~28s later; overlap prevented)
  Node started                                 (previous config restored)
  

• No Fatal signal, SIGABRT or tombstone appeared in logcat across any of the runs above.
• CI: standard compile, unit test, and detekt checks run by the PR bot.